<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   <meta name="Author" content="Johannes Sixt">
   <title>KDbg - User's Manual</title>
</head>
<body text="#000000" bgcolor="#FFFFFF">

<h1>
KDbg - User's Manual</h1>

<h2>
Contents</h2>

<ul>
<li>
<a href="#Introduction">Introduction</a></li>

<li>
<a href="#UsingKDbg">Using KDbg</a></li>

<li>
<a href="#InfoWindows">KDbg's information windows</a></li>

<li>
<a href="#Tips">Tips and such</a></li>

<li>
Advanced topic: <a href="types.html">Type tables</a></li>

<li>
<a href="invocation.html">How to invoke KDbg from the command line</a></li>

<li>
<a href="#Author">Author</a></li>
</ul>

<hr>
<h2>
<a name="Introduction"></a>Introduction</h2>
<p>KDbg is a front-end for <tt>gdb</tt>, the GNU debugger.</p>
<p>This means that KDbg itself is not the debugger. Rather, it communicates
with <tt>gdb</tt>, a command line debugger, by sending commands to it and
receiving the output, such as variable values. The menu commands and mouse
clicks are translated into <tt>gdb</tt> commands, and the output of <tt>gdb</tt>
is translated into (more or less) visible information, such as structured
variable contents.</p>
<p>The upshot of all this is that KDbg completely relies on the capabilities
of the underlying command line debugger, <tt>gdb</tt>. KDbg can do no more
than <tt>gdb</tt> can. For example, if you have a <tt>gdb</tt> that does
not supports debugging of threaded programs, KDbg cannot, either (even
though it offers a threads window).</p>
<h2>
<a name="UsingKDbg"></a>Using KDbg</h2>
<p>Before you start using KDbg, you may want to review the options in the
<a href="globaloptions.html">Global Options</a> dialog that you invoke
with <i>Settings|Global Options</i>.</p>
<h4>
Specifying a debugging target</h4>
<p>To debug a program, choose <i>File|Load Executable</i> from the menu. If you
have debugged the program earlier, you can choose it from <i>File|Recent
Executables</i>. The program is loaded.</p>
<p>If you want to debug a core dump, you must first load the executable
that produced the core dump, then choose
<i>File|Core Dump</i> from the
menu. Now KDbg goes to the point in the program that caused the core dump.</p>
<p>You can now set breakpoints, using the <i>Breakpoint</i> menu, the right
mouse button menu, or the <a href="breakptlist.html">breakpoint window</a>.</p>
<p>You can also choose program specific settings that apply only to the
currently loaded executable using <i>Settings|This Program</i>, in the
<a href="pgmsettings.html">Program Settings</a> dialog.</p>
<p>Furthermore, it is possible to <a href="xslt.html">debug XSLT scripts</a>.</p>
<h4>
Running the program</h4>
<p>Now run the program by selecting <i>Execution|Run</i>. The program now
executes as usual until it either exits, hits a breakpoint or watchpoint,
or receives a signal.</p>
<p>You can run the program with arguments, set a working directory, or
set environment variables. To do this, choose <i>Execution|Arguments</i>
and specify your options in the <a href="argspwdenv.html">Program Arguments</a>
dialog (before you start the program).</p>
<p>You can also attach to a program that is currently running. To do this,
first load the executable file like above. Then choose <i>Execution|Attach</i>.
From the list processes specify the one you want to attach to
and click <i>OK</i>. The running program is
halted (not terminated), and the current point of execution is displayed
in the source window.</p>
<p><font size="-1">On some systems the list of processes may not be available.
In this case a simple edit box is available where the process number can be
specified.</font></p>
<h4>
The program stopped - now what?</h4>
<p>When the program stops at a breakpoint, watchpoint, or due to a signal,
the <a href="sourcecode.html">source code window</a> displays the line
where the program stopped. It is very common that the program stops due
to a signal (usually a <tt>SIGSEGV</tt>, segmentation violation) in a function
that is not part of the program, that you have written. In this case you
investigate the <a href="stack.html">stack window</a> and look for a function
that you have written (start at the top of the list) and click on it. This
will bring you to a location that you can start your search for the real
bug.</p>
<p>In the menu <i>Execution</i> you find the commands that you need to
run
the program, step through code, and to interrupt the program (<i>Break</i>)
while it is running. The important commands (<i>Run</i> and all kinds of
<i>Step</i>) are bound to function keys. For efficient debugging it is
strongly recommend that you get used to using them. You can use
<i>Settings|Configure Shortcuts</i> if you want to bind the functions
to different keys.</p>
<p>In the menu <i>Breakpoint</i> you find commands to set, clear, disable,
and enable permanent and temporary breakpoints. You can display a list
of breakpoints in the <a href="breakptlist.html">breakpoints window</a>.
You can also set a breakpoint by clicking at the left end of the source
line (using the left mouse button), and you can enable and disable a breakpoint
by clicking it using the middle mouse button.</p>
<p>The animation in the toolbar indicates whether the program
is running. It stops when the program stopped in a breakpoint or for
some other reason or when the program exited. This animated button is a shortcut
for <i>Execution|Break</i>.</p>
<h2>
<a name="InfoWindows"></a>KDbg's information windows</h2>
<p>KDbg displays information and accepts commands in number of different windows.
In the menu <i>View</i> you find commands to show and hide these windows.
They are docking windows, which means that you can drag them around and
arrange them in any manner you like.</p>
<ul>
<li>
<a href="sourcecode.html">The source code window</a></li>

<li>
<a href="localvars.html">The local variables window</a></li>

<li>
<a href="stack.html">The stack window</a></li>

<li>
<a href="watches.html">The watched expressions window</a></li>

<li>
<a href="breakptlist.html">The breakpoint list</a></li>

<li>
<a href="pgmoutput.html">The output window</a></li>

<li>
<a href="registers.html">The register dump window</a></li>

<li>
<a href="memory.html">The memory dump window</a></li>

<li>
<a href="threads.html">The threads window</a></li>
</ul>

<h2>
<a name="Tips"></a>Tips and such</h2>
<p>The following topics give some useful hints on using KDbg.</p>
<ul>
<li>
<a href="tips.html">Tips and Tricks</a></li>

<li>
<a href="howdoi.html">How do I...?</a></li>
</ul>

<h2>
<a name="Author"></a>Author</h2>
<p>KDbg is written by <a href="mailto:j6t@kdbg.org">Johannes Sixt</a>
with contributions from many people, among others (in no particular order):</p>
<ul>
<li>Marc Font Freixa</li>
<li>Michael Hansen</li>
<li>Daniel Black</li>
<li>Max Tomilov</li>
<li>Charles Samuels</li>
<li>David Edmundson</li>
<li>Stefan Taferner</li>
<li>Keith Isdale</li>
<li>Daniel Thor Kristjansson</li>
<li>Matthew Allen</li>
</ul>
<p>KDbg homepage is at <a href="http://www.kdbg.org/">http://www.kdbg.org/</a>.</p>
</body>
</html>
